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NETWORK FORTRAN SUBPROGRAMS 


Preface 


The subroutines described in this document have been implemented at 
UCSB and make the Network (via the NCP) accessible to Fortran 
programs executing in the 360/75. They are callable from within any 
Fortran main program or subroutine compiled at UCSB. 
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A set of assembly-language written subprograms is provided to 
facilitate the sue of the Network by FORTRAN programmers. They serve 
as an interface between the user and the Network Control Program 
(NCP), which supervises all Network operations at this site. 


A concept fundamental to FORTRAN Network operations is that of a 
completion code variable. Associated with each socket that is not in 
the closed state is a unique variable, called a completion code 
variable. This variable serves two purposes: it identifies the local 
socket referenced, and upon completion of the operation it contains a 
completion code to indicate the outcome of the operation to the 


programmer. It may be used at any time for any purpose other than 
network operations. Its value at the beginning of a Network 
operation is immaterial; rather it is the variable itself that is 
important. In all Network operations, whenever a completion code 
variable is called for, the only acceptable type variable is 
INTERGER*4. 


In general, the subprograms will initiate the operation, and enter 
the WAIT state (consume no CPU time) until notified by the NCP of the 
completion of the operation. For such operations, the programmer 
supplies a time limit, of type INTERGER*4, which specifies, in tenths 
of a second, the maximum length of time the subprogram is to wait for 
the operation to complete. If this time limit is exceeded, a 
completion code is supplied to indicate the error; and control is 
returned to the calling program, with the operation still pending. 


In those operations requiring a socket to be specified by its socket 
identifier, the following format is used. The identifier is 
specified as a INTEGER*4 array with at least two elements, or an 
element of such an array. The first element specified is taken to be 
the site number, and the next element the socket number. A socket 
number may have any value, positive, negative, or zero. Since 
negative numbers are represented internally in two’s complement form, 
for the purposes of the gender of a socket, a socket number is even 
for odd according to whether its absolute value is even or odd, 
respectively. 


Following is a description of each subprogram, its function and 
calling sequence. 


(1) OPEN 


By invoking this subprogram, the user requests that the specified 
local socket be removed from the closed state and thus be 
prepared to participate in data transfer. There are three 
distinct operations that can be performed by this subprogram, and 
these are described below: 
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CONNECT 


By initiating this operation, the user requests that the 
specified local socket be logically connected to the 
specified foreign socket, and that data transfer between the 
two sockets be enabled. The subprogram will wait until the 
foreign socket either accepts or rejects the connection 
attempt. This operation is valid only when the local socket 
is in the closed state. 


The calling sequence is as follows: 
CALL OPEN (cmpcd, time, lclsck, fgnsck, ws) 


where 
‘cmpcd’ is the completion code variable to be associated 
with the local socket. 


‘time’ is the length of time the subprogram is to wait 
for the completion of the operation. 


‘lclsck’ is the socket identifier of the local socket. 
'fgnsck’ is the socket identifier of the foreign socket. 


‘ws’ is a workspace, which as the same attributes as a 
socket identifier, and, if the operation is 
successful, will become associated with the local 
socket for the life of the connection. In response 
to certain future operations, information may be 
returned to the programmer in this workspace. 


The following completion codes are possible for this 
operation: 


0, The operation was successful and the connection 
has been established 


4, The specified completion code variable is 
already assigned to a socket; the operation was 


suppressed 


8, The specified local socket is not in the closed 
state; the operation was suppressed 


12, All communication paths to the specified foreign 
site are in use; the operation was suppressed 
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16, Local resources are insufficient to support 
another connection; the operation was suppressed 


20, The connection attempt was rejected by the 
foreign process 


24, The specified local socket is not local to UCSB; 
the operation was suppressed 


28, The specified foreign site is invalid; the 
operation was suppressed 


32, An addressing or protection exception was 
encountered with respect to the specified 
workspace; the operation was suppressed 


36, Either hardware at the foreign site is 
inoperative or the NCP’s counterpart at the 
foreign site does not exist or has failed 


40, Local and foreign sockets are both either send 
or receive sockets; the operation was suppressed 


44, By operator command, all Network operations were 
terminated; the socket will be closed 


60, An NCP control transmission error occurred; the 
operation was suppressed 


252, The specified time limit was exceeded; the 
operation was initiated but not completed 


LISTEN 


This operation is a request for notification of any 
connection attempt directed toward the specified local 
socket. The subprogram waits until such a call is received, 
at which time the calling processes’ socket identifier is 
returned to the calling program. This operation is valid 
only when the designated local socket is in the closed state. 


The calling sequence is as follows: 
CALL OPEN (cmpcd, time, lclsck, ws) 
Where 


‘cmpcd’ is the completion code variable to be associated 
with the local socket. 
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‘time’ 


is the length of time the subprogram is to wait 


for the completion of the operation. 


A VNCESCKY 


is the socket identifier of the local socket. 


‘ws’ is a workspace which, if the operation is 
successful, will contain the socket identifier of 
the calling socket, and will become associated with 
the local socket for the life of the connection. 
‘ws’ has the same attributes as a socket 
identifier. 


The following completion codes are possible for this 
operation: 


0, 


16, 


20, 


44, 


252, 


(C) ACCEPT 


The operation was successful and a call has been 
received 


The specified completion code variable is 
already assigned to a socket; the operation was 
suppressed 


The specified local socket is not in the closed 
state; the operation was suppressed 


Local resources are insufficient to support 
another connection; the operation was suppressed 


The specified local socket is not local to UCSB; 
the operation was suppressed 


An addressing or protection exception was 
encountered with respect to the specified 
workspace; the operation was suppressed 


By operator command, all Network operations were 
terminated; the socket will be closed 


The specified time limit was exceeded; the 
operation was initiated but not completed 


This operation accepts connection with the foreign socket 
whose call caused successful completion of a previous LISTEN 
operation by the specified local socket. After completion of 
this operation, data may be transferred to or from the local 
socket, depending on its gender. This operation is valid 
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only when the last operation referencing the local socket was 
a LISTEN operation. The subprogram will wait until the 
operation is completed. 


The calling sequence is as follows: 
CALL OPEN (cmpcd, time) 


Where 
‘cmpcd’ is the completion code variable associated with 
the local socket by a previous LISTEN operation. 


‘time’ is the length of time the subprogram is to wait 
for the completion of the operation 


The following completion codes are possible for this 
operation: 


0, The operation was successful, and the connection 
is established 


4, The specified local socket is in the closed 
state 9The NCP may have received an abort 
notification from the foreign process); the 
operation was suppressed 


8, the previous operation specifying the designated 
local socket was not a LISTEN; the operation was 
suppressed 


12, All communication paths to the specified foreign 
site are in use; the socket has been returned to 
the closed state 


252, the specified time limit was exceeded; the 
operation was initiated but not completed 


CLOSE 


This operation is a request that the specified local socket be 
returned to the closed state. If the last operation involving 
this socket was a LISTEN, this operation refuses the foreign 
process’ connection attempt. If the last operation was CONNECT, 
the attempt is aborted. If a connection is established, any data 
in transit from the local socket is allowed to reach the foreign 
socket to be either received or flushed before the local socket 
is closed. The subprogram will wait until the socket has been 
returned to the closed state. 
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The calling sequence is as follows: 
CALL CLOSE (cmpcd, time) 


Where 


'cmpcd’ is the completion code variable associated with 
the local socket. 


‘time’ is the length of time the subprogram is to wait 
for the completion of the operation. 


The following completion codes are possible for this operation: 


0, the operation was successful, and the socket has 
been returned to the closed state 


8, The specified completion code variable is not 
currently assigned to a socket; the operation 
was suppressed 


12, The specified local socket is in the process of 
being closed; the operation was suppressed, but 
the local socket will be closed 


36, Either hardware at the foreign site is 


inoperative, or the NCP’s counterpart at the 
foreign site does not exist or has failed 
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44, By operator command, all Network operations were 
terminated; the socket will be closed 


60, An NCP control transmission error occurred; the 
operation was aborted 


64, A transmission error occurred; the operation was 
aborted, but the socket will be closed 


252, The specified time limit was exceeded; the 
operation was initiated but not completed 


3) SEND 


This program causes data to be sent to the foreign socket. The 
subprogram will wait until the data has been received by the 
foreign socket, or until it has been queued locally by the NCP. 


The calling sequence is as follows: 
CALL WRITE (cmpcd, bfr, len, time [,offset]) 
Where 
‘'cmpcd’ is the completion code variable associated with 


the local socket. 


'bfr’ is the data to be sent, and can be of any type, 
any length. 


‘len’ is the number of bits of data to be sent. If 
‘len’ is non-positive, no operation is performed. 
‘len’ is of type INTEGER*4. 


‘time’ is the length of time the subprogram is to wait 
for the completion of the operation. 


‘offset’ is the bit offset from the first bit of 'bfr’ 
at which data transmission is to begin, and is of 
type INTEGER*4. If not specified, '’offset’ 
defaults to zero. 


The following completion codes are possible for this operation: 


0, The operation was successful, and the data has 
been sent 


4, The specified local socket is not a send socket; 
the operation was suppressed 
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8, 


12, 


16, 


20, 


36, 


44, 


52, 


56, 


60, 


64, 


252, 


4) RECEIVE 


The specified completion code variable is not 
assigned to a socket; the operation was 
suppressed 


A previous send operation is in progress; the 
operation was suppressed 


The connection is not fully open; the operation 
was suppressed 


The foreign socket terminated the connection 
before completion of the send operation; not all 
the data was transmitted 


Either hardware at the foreign site is 
inoperative, or the NCP’s counterpart at the 
foreign site does not exist or has failed 


By operator command, all Network operations were 
terminated; the socket will be closed 


One or more interrupts were received from the 
foreign socket; the operation was suppressed 


An addressing exception was encountered with 
respect to the data buffer; the operation was 
suppressed 


An NCP control transmission error occurred; the 
operation was aborted and the socket will be 
closed 


A transmission error occurred; the operation was 
aborted and the socket will be closed 


The specified time limit was exceeded; the 
operation was initiated but not completed 


This operation causes data to be received from the foreign 
socket. The subprogram will wait until the reception of data is 


complete. 


The calling sequence is as follows: 


CALL READ 
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(cmpcd, bfr, len, time [,offset]) 
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Where 
‘cmpcd’ is the completion code variable associated with 
the local socket. 


'bfr’ is the variable into which the data is to be 
placed, and can be of any type, any length. 


‘len’ is the number of bits of data to be received. If 
‘len’ is non-positive, no operation is performed. 
‘len’ is of type INTEGER*4. 


‘time’ is the length of time the subprogram is to wait 
for the completion of the operation. 


‘offset’ is the bit offset from the first bit of ’bfr’ 
at which the first bit of data is to be placed, and 
is of type INTEGER*4. If not specified, the 
‘offset’ defaults to zero. 


The following completion codes are possible for this operation: 


0, The operation was successful and the data has 
been received 


4, The specified local socket is not a receive 
socket; the operation was suppressed 


8, The specified completion code variable is not 
assigned to a socket; the operation was 
suppressed 


12, A previous receive operation is in process; the 
operation was suppressed 


16, The connection is not fully open; the operation 
was suppressed 


20, The foreign socket terminated the connection 
before completion of the receive operation; data 
is unpredictable 


24, An addressing or protection exception was 
encountered with respect to the data buffer; the 
operation was suppressed 


36, Either hardware at the foreign site is 


inoperative, or the NCP’s counterpart at the 
foreign site does not exist or has failed 
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44, By operator command, all network operations were 
terminated; the socket will be closed 


52, One or more interrupts were received from the 
foreign socket; the operation was suppressed 


60, An NCP control transmission error occurred; the 
operation was suppressed and the socket will be 
closed 


252, the specified time limit was exceeded; the 
operation was initiated but not completed 


5) CHECK 
This operation causes the status of the specified local socket to 
be returned. There is no completion code variable associated 
with this operation, since it is always successful and the socket 
is identified by its socket number. This operation is valid at 
any time and is always completed immediately. 
The calling sequence is as follows: 


CALL CHECK (lclsck, stat, menu, fgnsck, deficit) 


Where 
‘lclsck’ is the socket identifier of the local socket. 


‘stat’ is a code for the status, and is of type 
INTEGER*4. 


‘mnem’ is a mnemonic for the status, and can be of any 
type, of any length greater than or equal to eight 
bytes. 


'fgnsck’ is the socket identifier of the foreign socket, 
or zero. 


‘deficit’ is the send/receive deficit in bits, or zero, 
and is to type INTEGER*4. 


‘lclsck’ is the only argument the programmer need 
define; the others are output from the subprogram. 
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4 CALL (S) 
5 I/O 
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` 


MEANING 

A connection is fully established. No 
SEND/RECEIVE operation is in progress. 
fgonsck’ is the socket identifier of the 
connected socket. ‘deficit’ is the number of 
bites queued locally at the socket by the NCP 
and available to satisfy a future RECEIVE 
operation, or awaiting output ads the results 
of a previous SEND operation. 


A LISTEN has been issued. 


A CONNECT has been issued. ’fgnsck’ is the 
socket identifier of the foreign socket. 


A LISTEN has been completed. ‘’fgnsck’ is 
the socket identifier of the calling socket. 


One or more calls have been received for the 
local socket. No LISTEN or CONNECT has been 
issued. 


A connection is fully established. A 
SEND/RECEIVE operation is in progress. 
fgnsck’ is the socket identifier of the 
connected socket. ‘deficit’ is the number 
of bits yet to be sent or received. 


The socket is in the closed state. 


The foreign socket is attempting to close the 
connection. The NCP has data yet to be ready 
by the local socket. ‘’fgnsck’ is the socket 
identifier of the connected socket. 

deficit’ is the number of bits yet to be 
received. 


The foreign socket is attempting to close the 
connection. The NCP is awaiting arrival at 
the foreign site of data currently in 
transit. ‘’fgnsck’ is the socket identifier 
of the connected socket. 


The local socket has issued a CLOSE. The NCP 
is in the process of returning the local 
socket to the closed state. ’fgnsck’ is the 
socket identifier of the connected socket. 
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10 DRAIN--> The local socket has issued a CLOSE. The NCP 
is completing the last SEND operation before 
returning the local socket to the closed 
state. ‘’fgnsck’ is the socket identifier 
of the connected socket. ’deficit’ is the 
number of bits the NCP has yet to transmit. 


(6) IDENTIFY 
This operation is used to identify a local socket by its 
completion code variable. The operation is valid at any time, 
and is always completed immediately. Since it is always 
successful, there are no completion codes for the operation, and 
the contents of the completion code variable are not changed. 


The calling sequence is as follows: 


CALL ID (cmpcd, lclsck) 


Where 

‘'cmpcd’ is the completion code variable associated with 
the local socket. 

‘lclsck’ is set to the socket identifier of the local 
socket if the completion code variable is 
associated with a socket, or to zero otherwise. 

(7) SIGNAL 


This operation is used to convey a signal to the foreign process. 
The significance of the signal is completely user-dependent. The 
effect is that the next time the foreign socket attempts to 
initiate a RECEIVE or SEND operation, the operation will be 
suppressed, and a completion code supplied indicating that a 
signal had been received. The subprogram will wait until the 
signal has been sent to the foreign NCP. This operation is valid 
only when the socket is fully open. 


The calling sequence is as follows: 
CALL SIGNAL (cmpcd, time) 
Where 
‘'cmpcd’ is the completion code variable associated with 


the local socket. 


‘time’ is the length of time the subprogram is to wait 
for completion of the operation. 
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The following completion codes are possible for this operation: 


0, The operation was successful, and the signal has 
been sent 


4, The specified completion code variable is not 
assigned to a socket; the operation was 
suppressed 


8, The connection is not fully open; the operation 
was suppressed 


Certain of the Network subprograms are intended for, although not 
restricted to, use with the Online System Network operators. The 
following is a general description of these operators: 


In all Network operations involving the Online System Network 
operators, there are certain conventions concerning the format 
of the data sent and received. The data is grouped in 
‘messages’ consisting of three fields, op code, length, and 
text, in that order. The op code is one byte in length and is 
a code which indicates how the text field is to be 
interpreted. The length field is two bytes long, and gives 
the length, in bits, of the text fields, which contains the 
actual data. (The op code and length fields together are 
termed a header.) 
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The following op codes are presently defined: 
Op Code Meaning 


0 This op code is a NOP. No text field exists, and the 
contents of the length field are unpredictable. (This 
op code is used mainly as a delimiter.) 


1 The text field contains EBCDIC characters, one 
character per byte. The Online System operators 
consider the characters as intended for display as soon 
as the text field has been received. 


2 The text contains codes for keypushes, one byte per 
key. The Online operators consider the keys as 
intended for execution as soon as the text field has 
been received. 


3 The same as for an op code of 2, except that the Online 
operators consider that the execution of the keys will 
be delayed until all data for that receive operations 
has been received. 


The standard format of data sent or received by the Online System 
operators is a string of messages, with the last message 
indicated by a header with a NOP op code, called a trailer. 

These conventions are the default situation; any of them may be 
overridden by appropriate programming. 


Following are descriptions of those subprograms intended for use 
the Online System operators. 


(8) WRITE TO ONLINE CONSOLE 


This subprogram causes data, assumed to be characters represented 
by their EBCDIC codes, to be sent from the specified local 
socket. The characters are sent in a standard message, preceded 
by a header, and optionally followed by a trailer. The 
subprogram waits for the data to be received by the foreign 
socket, or to be queued locally by the NCP. This operation is 
valid only when the local socket is a send socket, and is fully 
open. 
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The calling sequence is as follows: 


CALL WTOLC (cmpcd, bfr, len, level, across, down, time) 


Where 


‘cmpcd’ is the completion code variable associated with 


pEr” 


‘len’ 


the local socket. 


is the character string to be sent, and can be of 
any type, any length. 


in absolute value, is the number of characters to 
be sent. If ’len’ is positive or zero, the end of 
the data is indicated by a trailer; if ’len’ is 
negative, no trailer is sent. ‘len’ is of type 
INTEGER*4. 


‘level’ indicates the mode of typing. The absolute 


value of ’level’, if non-zero, is the shift level 
on which to type, and must be less than or equal to 


nine. If greater than nine, one is sued. If 
‘level’ is positive, '’across’ and '’down’ are 
relative to the current typing location. If 


‘level’ is negative, the carriage is positioned to 
the upper left-hand corner before typing begins, 
thus making ‘across’ and ’down’ absolute 
coordinates. If ’level’ is zero, the tying is in 
case one characters, and a carriage return precedes 
the positioning for ’across’ and ’sown.’ If the 
characters to be displayed are case one characters, 
the header sent will have an op code which 
indicates characters to be displayed as soon as 
they are received; otherwise, the op code will 
indicate buttons to be executed as soon as 
received. ’level’ is of type INTEGER*4. 


‘across’ is the number of spaces to be moved 


horizontally across the display tube before 
beginning to type. across’ can have any value, 
positive, negative, or zero, and is type INTEGER*4. 


‘time’ is the length of time the subprogram is to wait 
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The completion codes for this operation are the 
same as for SEND. 
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(9) READ FROM ONLINE CONSOLE 


This subprogram receives data, assumed to be characters 
represented by their EBCDIC codes, from the foreign socket in one 
or more standard messages. The subprogram will wait for the 
data, optionally followed by a trailer, to be received by the 
local socket. This operation is valid only when the local socket 
is a receive socket and is fully open. 


The calling sequence is as follows: 
CALL RFOLC (cmpcd, bfr, len, time) 


Where 


‘cmpcd’ is the completion code variable associated with 
the local socket. 


'bfr’ is the variable into which the data is to be 
placed, and can be of any type, any length. 


‘len’, in absolute value, is the maximum number of 
characters to be placed in /’bfr’. If the length 
fields of the head(s) received total more data than 
‘len’, the excess data will be received, but will 
not placed into ’brf’, and will not be accessible 
to the program. If ’len’ is positive or zero, data 
will be received until a trailer is encountered. 

If ’len’ is negative, a single message, exclusive 
of trailer, will be received. ’len’ is of type 
INTEGER*4. 


‘time’ is the length of time the subprogram is to wait 
for completion of the operation. 


The completion codes for this operation are the 
same as for RECEIVE. 


(10) WRITE TO ONLINE CONSOLE WITH REPLY 


This subprogram combines the functions of ’/WRITE TO ONLINE 
CONSOLE’ and ’READ FROM ONLINE CONSOLE’. The subprogram first 
sends a string of data to the foreign socket form the specified 
send socket, waits for it to be received by the foreign socket 
(or queued locally by the NCP), and then waits for a reply 


directed toward the specified receive socket. The operation is 
valid only when the sockets have the correct gender and both are 
fully open. 
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The calling sequence is as follows: 


CALL WTOLCR (cmpcd, bfr, len, level, across, down, time, 
cmpcd2, bfr2, len2) 


Where 

’cmpcd’ is the completion code variable associated with 
the local send socket. 

'bfr’ is as in ’WRITE TO ONLINE CONSOLE’. 

‘len’ is as in ’WRITE TO ONLINE CONSOLE’. 

‘level’ is an in ’WRITE TO ONLINE CONSOLE’. 

‘across’ as in ‘WRITE TO ONLINE CONSOLE’. 

‘down’ is as in ’WRITE TO ONLINE CONSOLE’. 

‘time’ is the length of time the subprogram is to wait 
for completion, individually, of the transmission 
and reception of data. 

‘cmpcd2’ is the completion code variable associated with 
the local receive socket. 

'brf2’ is as 'bfr’ in ’READ FROM ONLINE CONSOLE’. 

‘len2’ is as ’len’ in ’READ FROM ONLINE CONSOLE’. 

The completion codes for the send socket are the 
same as for the SEND operation, and the completion 
codes for the receive socket are the same as for 
the RECEIVE operation. 

(11) ERASE 


This subprogram cause data constituting on Online System command 
to erase the display tube to be sent from the specified local 
socket. The data is sent in a single standard message, including 
an op code indicating characters to be displayed as they are 
received, and optionally including a trailer. The subprogram 
waits for the data to be received by the foreign socket, or to be 
queued locally by the NCP. This operation is valid only when the 
local socket is a send socket, and is fully open. 


The calling sequence is as follows: 
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CALL ERASE (’cmpcd’, ‘’delayl’, ‘’delay2’, ‘time’ ) 


Where 


‘'cmpcd’ is the completion code variable associated with 
the local socket. 


‘delayl’, in absolute value, is the length of time, in 
tenths of a second, the subprogram is to pause (in 
the WAIT state) before sending the erase. If 
‘delayl’ is positive or zero, a trailer will be 
sent after the erase; if negative, no trailer will 
be sent. ‘’delayl’ is of type INTEGER*4. 


‘delay2’ is the length of time, in tenths of a second, 
the subprogram is to pause after sending the erase 
and before returning control to the calling 
program, and is of type INTEGER*4. 


‘time’ is the length of time the subprogram is to wait 
for completion of the operation. 


The completion codes for this operation are the 
same as for SEND. 
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